Autonomous Underwater Vehicles : trex - ODSS web API
This page last changed on Jun 05, 2013 by fpy.
This working document is used to specify how T-REX will present a web API in order to easily be connected to ODSS (or any other software). The document will evolve as our work advance and start from a very high level specification at first down to much more precise API definition.
Initial service calls considered.
As a first step we propose the following simple calls (To be refined as implementation is done):
 |
In this initial version neither the format of the web request or the data structure is defined. Principle on request arguments:
|
General services
get short help
get short help
- format:
- GET http://<host>/rest/help
- GET http://<host>/rest/help/{cmd-path}
- Gets the list of services – under {cmd-path} if provided – along with a short help message
- output example: GET http://<host>/rest/help/help
{ "help": [ { "href": "\/rest\/help", "info": "List REST commands availables.\nArgument restrict the help to command matching given path." } ] }
TREX version
TREX version
- format:
- GET http://<host>/rest/version
- Gets information of the currently running version of trex
- output:
{ "version_major": "0", "version_minor": "5", "version_release": "0", "version_rc": "1", "svn_root": "trunk", "svn_rev": "1450", "version_str": "0.5.0-rc1 (svn:trunk[1450])" }- note svn_rev may not be a integer but is the output of the svnversion command. Which mean that ift can be a range of version (eg 1447:1450) and/or be postfixed by a modification flag letter (M for locally modified, S for a branch of tag instead of the trunk)
Tick and date related services
Current tick
Current tick
- format: GET http://<host>/rest/tick
- Give information about the next tick of trex
- output: GET http:://<host>/rest/tick
{ "value": "2656", "date": "2013-06-04T15:29:04.923976" }- value : the tick value as represented by trex
- date : the corresponding UTM date
Next tick
Next tick
- format: GET http://<host>/rest/tick/next
- Give information about the current tick of trex
- output: GET http:://<host>/rest/tick/next
{ "value": "2658", "date": "2013-06-04T15:31:04.923976" }- value : the tick value as represented by trex
- date : the corresponding UTM date
Initial tick
Initial tick
- format: GET http://<host>/rest/tick/initial
- Give information about the first tick of trex (usually 0)
- output: GET http:://<host>/rest/tick/initial
{ "value": "0", "date": "2013-06-02T19:13:04.923976" }- value : the tick value as represented by trex
- date : the corresponding UTM date
Final tick
Final tick
- format: GET http://<host>/rest/tick/final
- Give information about the last tick of trex. The last tick of trex is the date where it will quit.
- output: GET http:://<host>/rest/tick/final
{ "value": "1000000", "date": "2015-04-28T05:53:04.923976" }- value : the tick value as represented by trex
- date : the corresponding UTM date
tick info
tick info
- format: GET http://<host>/rest/tick/{number}
- Give information about the tick {number}
- output example: GET http:://<host>/rest/tick/2658
{ "value": "2658", "date": "2013-06-04T15:31:04.923976" }- value : the tick value as represented by trex
- date : the corresponding UTM date
tick at a date
tick at a date
- format: GET http://<host>/rest/tick/at/{date}
- Give information about the largest tick before or at the provide UTC {date}
- output example: GET http:://<host>/rest/tick/at/2014-01-01
{ "value": "305566", "date": "2013-12-31T23:59:04.923976" }- value : the tick value as represented by trex
- date : the corresponding UTM date
tick rate/duration
tick rate/duration
- format: GET http://<host>/rest/tick/rate
- Give information about the duration of a tick
- output: GET http:://<host>/rest/tick/rate
{ "nanoseconds": "60000000000", "duration": "00:01:00" }- nanoseconds : the duration in ns
- duration : same duration as [H*]HH:MM:SS[.SUBSECOND]
Wait for new tick
Wait for new tick
- format: GET http://<host>/rest/tick/wait
- This request implements a long pull in order for the client to be notified when the next tick occurs.
The request will not respond until the next tick occurs. - output: similar to GET http://<host>/rest/tick
Timelines and goals services
List of trex existing timelines
List of trex existing timelines
- format:
- GET http://<host>/rest/timelines
- GET http://<host>/rest/timelines/timline_a/timeline_b ...
- options:
- full=(0|1) set it to 1 in order to see all the timelines (including timelines with name starting with an underscore). Useful only when no timeline names are appended to the URL
- format=(tick|date) indicate whether data of from and to option are expressed as trex tick or ISO date. Default is date
- from=<tick_or_date> give a lower bound for the time window of interest. the value format depends on format option
- to=<tick_or_date> give a upper bound for the he time window of interest. the value format depends on format option
- example GET http://<host>/timelines?full=1&format=tick&from=10
- input: none
- output:
- a list of all the timelines trex currently have as a json object with a format as given in this example
{ "timelines": [ { "name": "dorado_state", "alive": "true", "accept_goals": "false", "latency": { "ticks": "0", "duration": "00:00:00" }, "look_ahead": { "ticks": "0", "duration": "00:00:00" }, "publish_plan": "false", "href": "/rest/timeline/dorado_state" }, { "name": "dorado_survey", "alive": "true", "accept_goals": "true", "latency": { "ticks": "0", "duration": "00:00:00" }, "look_ahead": { "ticks": "1", "duration": "00:01:00" }, "publish_plan": "false", "href": "/rest/timeline/dorado_survey" }, ... ] }
- a list of all the timelines trex currently have as a json object with a format as given in this example
-
- "timelines" is the table containing all the timelines descriptors
- A timeline descriptor have the following fields:
- "name" the symbolic name of the timeline
- "href" the URI pointing to the timeline (see "Content of timeline" below)
- "alive" a boolean indicating whether this timeline is still managed or "dead" (resulting on a Failed state)
- "accept_goals" a boolean indicating if this timeline accept goals or not (for example position updates on assets do not accept goals)
- "publish_plan" a boolean indicating if this timeline will publish its future when it has a plan or can only display its past and current state
- "latency" The expected maximum delay until a received goal on this timeline will be processed
- "look_ahead" How far ahead in the future this timeline is usually planned for
- "total_obs" Number of tokens for this token that overlaps from, to
- "obs_period" Average duration of tokens for this token that overlaps from, to
- booth look_ahead and latency are json object giving their value both in term of TREX tick and real-time duration
- notes:
- The set of timelines may be dynamic and can grow as time advance (e.g. A new asset is added dynamically). Similarly all the attached information (except for their name) can change as the mission advance (although we often avoid it).
- Only total_obs and obs_period are affected by the from and to options
- It is possible to restrict the set of timeline to a known subset by specifying them on the URI. For example get http://<host>/rest/a/b/c will give information of only a, b and c
Contents of a timeline
Contents of a timeline
- formats:
- GET http://<host>/rest/timeline/{name}
- GET http://<host>/rest/timeline/{name}?from={date}
- GET http://<host>/rest/timeline/{name}?from={date}&to={date}
- GET http://<host>/rest/timeline/{name}?to={date}&format=date
- GET http://<host>/rest/timeline/{name}?from={int}&to={int}&format=tick
- input:
- {name} the name of the timeline
- format the format used to specify from and to . Possible formats are:
- date : from and to are specified as date (eg 2013-06-03T16:04:57.330-07:00)
- tick : from and to are given as integer which are directly trex tick values
- If not specified the default format is date
- from lower bound of the time window of interest (optional)
- to upper bound of the time window of interest (optional)
- when to is not specified it is set to +infinity, when from is not specified it is set to the current tick of -infinity if the specified to is in the past.
- output:
- The list of all the tokens of this timeline that overlaps the given time interval. Meaning all the token which
- can end after from (ie their largest possible end time is >= to from)
- can start before to (ie their smallest possible start time is <= to to)
- While the json format id still underwork here's an example of what I have now :
(the request: http://<host>/rest/timeline/dorado_survey?from=2013-06-03T16:04:57.330-07:00&to=2013-06-13T16:10:29.449-07:00){ "name": "dorado_survey" "requested_tick_range": { "int": { "max": "16077", "min": "1671" } }, "tokens": [ { "pred": "None", "on": "dorado_survey" "Variable": [ { "name": "start", "type": "date", "date": { "value": "2013-06-02T19:13:04.923976" } }, { "name": "end", "type": "date", "date": { "min": "2013-06-04T15:36:04.923976" } }, { "name": "duration", "type": "duration", "duration": { "min": "44:23:00" } } ] } ] } - In this example the result has the following attributes :
- "name" : The name of the timeline
- "alive" : Indicates if this timeline is currently still managed
- "requested_tick_range" : an interval giving the range [from, to] into ticks
- "token" : A table with all the tokens that match this range. Tokens are sorted by occurrence order
- The list of all the tokens of this timeline that overlaps the given time interval. Meaning all the token which
- error:
- 400: invalid request. The timeline name is either missing or non existent
- 400: parsing error from the optionals fields
- example:
- GET http://<host>/rest/timeline/dorado?from=2013-05-23&to=2013-05-31T12:00:00
- GET http://<host>/rest/timeline/dorado?from=0&to=100&format=tick
Post a new goal
Post a new goal
- format:
- POST http://<host>/rest/goal
- Associated data: the goal in json format (request header need to set Content-Type to application/json)
- example of a curl command:
curl -X POST --header 'Content-Type:application/json' -d ' { "on": "dorado_survey", "pred": "Track", "Variable": [ { "name": "drifter", "type": "enum", "enum": { "elem": [ { "value": "MBARI21" } ] } }, { "name": "lagrangian", "type": "bool", "bool": { "value": "1" } }, { "name": "path", "enum": { "elem": [ { "value": "square" } ] } }, { "name": "size", "float": { "value": 1000.0 } }, { "name": "start", "type": "date", "date": { "min": "2013-05-16T15:53:00" } }, { "name": "duration" "duration": { "max": "18:00:00" }, "type": "duration" } ] } }' http://<host>/rest/goal - output on success: A json structure with the following attributes:
- id : A unique identifier for the goal
- href: URL where this goal can be accessed (through GET or DELETE)
- Goal: The goal representation (should be fairly similar to what data was posted but with small tweaks such as updated start duration and end information)
- example output from the command above:
{ "id": "0xb0425cb0", "href": "/rest/goal/0xb0425cb0", "Goal": { "on": "dorado_survey", "pred": "Track", "Variable": [ { "enum": { "elem": [ { "value": "spotSim" } ] }, "type": "enum", "name": "drifter" }, { "bool": { "value": "1" }, "type": "bool", "name": "lagrangian" }, { "enum": { "elem": [ { "value": "square" } ] }, "type": "enum", "name": "path" }, { "float": { "value": "1000.0000000000000000" }, "type": "float", "name": "size" }, { "date": { "min": "2013-05-16T16:16:01.566673" }, "type": "date", "name": "start" }, { "date": { "min": "2013-05-16T16:17:01.566673" }, "type": "date", "name": "end" }, { "duration": { "min": "00:01:00", "max": "18:00:00" }, "type": "duration", "name": "duration" } ] } }
- error:
- 400: invalid request the goal is not well formatted
- note:
This feedback of this call only indicate whether the goal is properly formatted or not. An OK do not mean that the goal has been included in the plan yet (which is asynchronous and dynamic) but only that the reactors that manage the associated timeline has been notified of this new goal
Modify an existing goal
Modify an existing goal
- format:
- PUT http://<host>/rest/goal/{id}
- input:
- {id} the identifier of the goal as given by the response to a "Post new goal" command
- attachment: A json file describing the goal
- output:
- 200 OK
- error:
- 404: Goal not found (invalid goal id)
- 400: invalid request the goal is not well formatted
- note:
An OK does not mean that the goal has been updated in the plan yet (which is asynchronous and dynamic) but only that the reactors that manage the associated timeline have been notified of this new goalThis operation will not be implemented initially. For any modification, first DELETE then (re)POST the goal.
Cancel a goal
Cancel a goal
- format:
- DELETE http://<host>/rest/goal/{id}
- input:
- {id} the identifier of the goal as given by the feedback of "Post new goal" command
- output: none
- error:
- 400: unknown goal id
- effect:
- remove the goal with the associated id from the plan
This 3 simple calls will be the first basis of interaction. We envision later on to add extra calls as we see fit.
Push services envisioned
new plan
This service will notify the client whenever trex produced a new plan
As trex is composed to multiple planners, each of them dealing with its specific set of timlines. It may be better for the user to specify which set of timelines it want to be notified on similarly the event should give the set of timelines that have been updated
